Crate bevy_tweening
source · [−]Expand description
Tweening animation plugin for the Bevy game engine
🍃 Bevy Tweening provides interpolation-based animation between (“tweening”) two values, for Bevy components and assets. Each field of a component or asset can be animated via a collection or predefined easing functions, or providing a custom animation curve. Custom components and assets are also supported.
Example
Add the tweening plugin to your app:
use bevy::prelude::*;
use bevy_tweening::*;
App::default()
.add_plugins(DefaultPlugins)
.add_plugin(TweeningPlugin)
.run();
Animate the position (Transform::translation
) of an Entity
:
// Create a single animation (tween) to move an entity.
let tween = Tween::new(
// Use a quadratic easing on both endpoints.
EaseFunction::QuadraticInOut,
// Loop animation back and forth.
TweeningType::PingPong,
// Animation time (one way only; for ping-pong it takes 2 seconds
// to come back to start).
Duration::from_secs(1),
// The lens gives access to the Transform component of the Entity,
// for the Animator to animate it. It also contains the start and
// end values respectively associated with the progress ratios 0. and 1.
TransformPositionLens {
start: Vec3::ZERO,
end: Vec3::new(1., 2., -4.),
},
);
commands
// Spawn a Sprite entity to animate the position of.
.spawn_bundle(SpriteBundle {
sprite: Sprite {
color: Color::RED,
custom_size: Some(Vec2::new(size, size)),
..Default::default()
},
..Default::default()
})
// Add an Animator component to control and execute the animation.
.insert(Animator::new(tween));
Tweenables
🍃 Bevy Tweening supports several types of tweenables, building blocks that can be combined to form complex
animations. A tweenable is a type implementing the Tweenable
trait.
Tween
- A simple tween (easing) animation between two values.Sequence
- A series of tweenables executing in series, one after the other.Tracks
- A collection of tweenables executing in parallel.Delay
- A time delay.
Chaining animations
Most tweenables can be chained with the then()
operator to produce a Sequence
tweenable:
let tween1 = Tween::new(
// [...]
);
let tween2 = Tween::new(
// [...]
);
// Produce a Sequence executing first 'tween1' then 'tween2'
let seq = tween1.then(tween2);
Animators and lenses
Bevy components and assets are animated with tweening animator components, which take a tweenable and
apply it to another component on the same Entity
. Those animators determine that other component and
its fields to animate using a lens.
Components animation
Components are animated with the Animator
component, which is generic over the type of component
it animates. This is a restriction imposed by Bevy, to access the animated component as a mutable
reference via a Query
and comply with the ECS rules.
The Animator
itself is not generic over the subset of fields of the components it animates.
This limits the proliferation of generic types when animating e.g. both the position and rotation
of an entity.
Assets animation
Assets are animated in a similar way to component, via the AssetAnimator
component.
Because assets are typically shared, and the animation applies to the asset itself, all users of the asset
see the animation. For example, animating the color of a ColorMaterial
will change the color of all the
2D meshes using that material.
Lenses
Both Animator
and AssetAnimator
access the field(s) to animate via a lens, a type that implements
the Lens
trait.
Several predefined lenses are provided in the lens
module for the most commonly animated fields, like the
components of a Transform
. A custom lens can also be created by implementing the trait, allowing to animate
virtually any field of any Bevy component or asset.
Re-exports
pub use lens::Lens;
Modules
Collection of predefined lenses for common Bevy components and assets.
Structs
Component to control the animation of another component.
Component to control the animation of an asset.
A time delay that doesn’t animate anything.
A sequence of tweens played back in order one after the other.
Single tweening animation instance.
Event raised when a tween completed.
Plugin to add systems related to tweening of common components and assets.
Enums
Playback state of an animator.
Describe how eased value should be computed.
Playback state of a Tweenable
.
Direction a tweening animation is playing.
Type of looping for a tween animation.
Traits
Describes a type that can linearly interpolate between two points.
Functions
Animator system for assets.
Animator system for components.